/*
 * Copyright 2008,2009,2010 Daniel Freitas
 * 
 * This file is part of DMF Generic DAO.
 * 
 * DMF Generic DAO is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General
 * Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any
 * later version.
 * 
 * DMF Generic DAO is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied
 * warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
 * details.
 * 
 * You should have received a copy of the GNU Lesser General Public License along with DMF Generic DAO. If not, see
 * <http://www.gnu.org/licenses/>.
 */
package com.googlecode.dmf.genericdao;

import java.io.Serializable;
import java.util.List;

import org.springframework.transaction.annotation.Propagation;
import org.springframework.transaction.annotation.Transactional;

/**
 * Provides a common interface for basic CRUD operations and queries.
 * 
 * @author <a href="mailto:daniel.mfreitas@gmail.com">Daniel Freitas</a>
 * @param <T>
 *            The domain object this DAO is responsible for.
 */
public interface GenericDao<T> {

    /**
     * Finds all object instances of the specified type.
     * 
     * @return A {@link List} containing all objects from the given class stored in the persistence layer, in no
     *         particular order.
     */
    @Transactional(propagation = Propagation.REQUIRED, readOnly = true)
    public List<T> findAll();

    /**
     * Finds all objects similar to the given example. In other words, finds all objects which property values match the
     * example's properties. Optionally, it is possible to filter properties from the criteria by providing their names
     * to the vararg argument. The object identifier is never used in the comparison.
     * 
     * @param example
     *            The object instance to be used as an example.
     * @param excludeProperty
     *            The properties to be ignored from the comparison.
     * 
     * @return A list with all the objects that matches the given example.
     */
    @Transactional(propagation = Propagation.REQUIRED, readOnly = true)
    public List<T> findByExample(T example, String... excludeProperty);

    /**
     * Finds an entity object by its identifier.
     * 
     * @param id
     *            The object id to be queried for.
     * 
     * @param <V>
     *            The type of the identifier.
     * 
     * @return The object of the specified type whose id matches the given key, or null if the id cannot be found.
     */
    @Transactional(propagation = Propagation.REQUIRED, readOnly = true)
    public <V extends Serializable> T findById(V id);

    /**
     * Synchronizes the object state to the underlying persistence storage, propagating changes made in the object.
     * 
     * @param o
     *            The object to be saved.
     * 
     * @return The object that has been made persistent. If the object was a new instance, the id property is now
     *         populated.
     */
    @Transactional(propagation = Propagation.REQUIRED)
    public T makePersistent(T o);

    /**
     * Removes the domain object instance from the persistence layer.
     * 
     * @param o
     *            The object to be removed.
     */
    @Transactional(propagation = Propagation.REQUIRED)
    public void makeTransient(T o);
}
